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1. Understanding Your Port 


This book shows you how to port your graphics code from one IRIS-4D 
Series workstation to another, and how to tune your code to take advantage 
of unique hardware features of each IRIS 4D. It makes two assumptions: 

• Your code is currently running on an IRIS-4D Series workstation. If it is 
running on an IRIS Series 2000 or 3000 workstation, see Porting 
Applications to the IRIS-4D Family. 

• The IRIS on which your code is currently running (the current machine), 
and the IRIS to which you want to port your code (the target machine) are 
running the same release of software from Silicon Graphics. To check 
which version your machine is running, type: 

versions 


The first line looks something like this: 

stdl Std Sys PD 1, 4D1-3.0 808-0003-005 

This tells you your machine is running release 4D1-3.0. If both machines 
are not running the same version of system software, see the Release 
Notes for each version. These documents describe porting issues between 
different versions of system software. 
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1.1 Developing a Porting Strategy 


All IRIS-4D Series workstations can run the same version of system 
software from Silicon Graphics. This means that UNIX, languages, and 
compilers are completely compatible across the 4D family. However, 
because some Graphics Library subroutines are dependent on the underlying 
hardware, there are some graphics differences between IRIS-4D Series 
workstations that affect the portability of your code. 

You can ensure that your application is completely portable from one 4D to 
another in two ways: 

® Use only the Graphics Library subroutines that are common to all 
members of the family. 

e Structure your code so it can use different subroutines depending on 
which 4D it is currently using. 

If you use the first approach, the same version of code will run on all 
machines without modification. However, in most cases, the Graphics 
Library subroutines that are specific to a particular IRIS 4D are those 
subroutines that greatly increase graphics performance or take advantage of 
unique features. If you use the second approach, your code will be 
completely portable, and will also take advantage of the unique features of 
each machine (see “Tools for Porting”, below). 

Each chapter of this book contains two sections. The first section shows you 
the changes (if any) that you must make to your current code so it will run 
on the target machine. If you are interested in maintaining the highest 
degree of portability and are not interested in increasing the performance of 
your code, this is the only section you need to read. The second section 
shows you how to take advantage of the subroutines that are specific to the 
machine that will make your code run faster. 
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1.2 Tools for Porting 


To help smooth your port, Silicon Graphics provides two special 
subroutines: gversionand glcompat. (Seethe GT Graphics Library 
User’s Guide for full descriptions.) 

gversion returns a value that specifies on which IRIS-4D 
(non-GT running 3.1 = GL4D-3.1, GT running 3.1 = GL4DGT-3.1, Personal 
IRIS running 3.1 = GL4DPI-3.1) the code is currently executing. Use this 
subroutine if you adopt the second porting approach that was mentioned 
above. 

By default, subroutines run on the target machine exactly as they do on the 
current machine. Use glcompat to turn off this compatibility mode. This 
may produce a slightly different visual effect, but may increase performance 
dramatically. See Section 2.2.2 for an example. 


1.3 The 4D Family Portrait 

This section shows where incompatibilities exist between different members 
of the 4D family. Subroutines cause incompatibilities when: 

• they are not supported by all machines 

• they work differently depending on which machine they are currently 
using 

Currently, differences exist between IRIS-4D Series workstations that have 
GT graphics (those models that have “GT” as part of their name), those 
that do not (those without “GT” in their name, excluding the Personal 
IRIS), and the Personal IRIS. This document refers to the different models 
as GT, non-GT, and Personal IRIS, respectively. 

The following table shows the subroutines that are supported by only the 
non-GT. 
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Non-GT Subroutines 


clearhitcode 

gethitcode 

get lsbackup 

getresetls 

gRGBcursor 

lsbackup 


resetls 

RGBcursor 

xfpt 

setslowcom 
setf astcom 


Table 1-1. Subroutines Supported by Only the Non-GT 

This table shows subroutines that are supported by the GT, Personal IRIS, 
and future IRIS-4D Series workstations. 


GT Subroutines 


*blendfunction 

lrectread 

lrectwrite 

readsource 

rectread 

rectwrite 


rectzoom 

smoothline 

zdraw 

zfunction 

zsource 

zwritemask 


Table 1-2. Subroutines Supported by the GT and future 4Ds 

Note: biendf unction runs on only those systems that have the optional 
alpha planes. 

This table shows the subroutines that work differently when they run on 
different machines. Each chapter describes their behavior on a specific 
machine. 


Subroutines with Different Behaviors 

feedback 

curveit 

endfeedback 

defpattern 

passthrough 

czclear 

zdraw 



Table 1-3. Subroutines that Work Differently on Different Machines 
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2e Porting 4D Code t© the GT 


There are two ways to approach a port to the GT. You can simply make 
your code run on the GT, or you can make it run faster by using the 
advanced features of the GT. This chapter is divided into two sections. The 
first section describes the changes you must make to non-GT code so that it 
will run on the GT. If you are not interested in further increasing the 
performance of your code, this is the only section you need to read. 

The second section gives you an overview of the new hardware and features, 
and shows you how to take advantage of them to enhance your code and 
make it run up to 10 times faster. For detailed information on all of the new 
subroutines, see the GT Graphics Library User’s Guide. 


2.1 Making Your Code Run on the GT 

To make your current non-GT code run on a GT, you need to follow two 
steps: 

1. Check whether the code uses any incompatible subroutines (see Section 
2.1.1,“ Summary of Incompatibilities’ ’.If it doesn’t, go to step 2. If it 
does use incompatible subroutines, see Section 2.1.2, “Working Around 
Incompatibilities”. 

2. Compile your code on any IRIS-4D using shared libraries. See section 
2.1.3, “Compiling Using the Shared Libraries”; for a full description of 
shared libraries, see the 4D1-3.0 Workstation Release Notes. 

After following these steps, you may notice two improvements: code that 
uses the Graphics Library subroutines for lighting model calculations runs 
up to 50 times faster, and, when a portion of a shaded object is not 
displayed, the workstation correctly clips the color data. See Section 2.2.1, 
“Overview of the GT Hardware”, for a full description. 
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2.1.1 Summary of Incompatibilities 

Non-GT code can be incompatible with the GT in two ways: 

• It uses subroutines that the GT does not support. 

• It uses subroutines or techniques that work differently on the GT. 

There are 1 1 subroutines that the non-GT support that the GT does not 
support. This table lists the subroutines and indicates into which category 
they fall. 


Subroutine 

Category 

getlsbackup 

line stippling 

lsbackup 


resetls 


getresetls 


RGBcursor 

cursors 

gRGBcursor 


xfpt 

feedback 

im subroutine 

immediate mode macros 

setfastcom 

terminal communication 

setslowcom 


clearhitcode 

hit codes 

gethitcode 



Table 2-1. Obsolete Subroutines 
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The GT supports the routines listed below, but they either return different 
values, cause different effects on the screen, or take different parameters. 


Subroutine 

Category 

feedback 

feedback 

endfeedback 


passthrough 


defpattern 

texture patterns 

curve it 

curves 

czclear 

clear screen, Z-buffer 


Table 2-2. Subroutines that Work Differently 

In addition, there are a few subroutines that were mistakenly visible from 
the 4D Graphics Library. They were never documented, and should have 
been used only internally. If any of the subroutines listed below appear in 
your code, remove them. 


gewrite 

tadelay 

zzsetfastcom 

zzsetslowcom 


2.1.2 Working Around Incompatibilities 

If your code contains any of the subroutines listed in Table 2-1, it will not 
link with the Graphics Library. Use these guidelines to eliminate the 
incompatible subroutines, then recompile the code using the shared libraries 
(see Section 2.1.3). 


Line Stippling 

resetls and getresetls let you reset the line style register. On the 
non-GT, move, draw, and all polygon drawing subroutines did not reset 
the line style (i.e., line stippling) between segments. On the GT, these 
subroutines automatically reset the line style between each pair of segments. 
If you need continuous stippling, you must restructure your code to use the 
new high performance drawing subroutines. See section 2.2.2, ‘ ‘Taking 
Advantage of the New Hardware”. 
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lsbackup and getlsbackup let you specify that the hardware draw the 
last pixel of any line, regardless of the line style pattern. These subroutines 
are not supported by the GT. If you need to make sure that the last pixel of 
a line is turned on, draw a point that has the same coordinates as the final 
vertex of the line segment. 


Hit Codes 

gethitcode and clearhitcode returned information about the plane 
against which clipping occurred. They are not supported by the GT. 


Cursors 

There has never been an RGB cursor in the 4D series, and RGBcursor { ) 
and getRGBcursor ( ) were replaced in that version of the Graphics 
Library by stubs that did nothing. If you are porting code from a non-GT to 
a GT, and your code contains either of these routines because it was ported 
from a 3000 series machine, change the references, to cursor or 
getcursor work as before. 


Feedback 

feedback, endfeedback, and passthrough are still supported, but the 
values they return are different on the GT. No forms of xf pt are supported 
by the GT. 

Feedback subroutines redirect the raw subroutine and data stream that 
comes out of the Geometry Engines to a feedback buffer, then returns it to 
the CPU process for interpretation. This means an application could access 
this information, but could use the information only if the application knew 
how to parse it. 

Because feedback information is completely dependent on the Geometry 
Engine hardware, whenever the Geometry Engines change, so does the 
feedback information. Code that uses the feedback mechanism may have to 
be re-written to parse the information differently every time the hardware is 
improved. If you have code that can easily be converted not to use the 
feedback mechanism, Silicon Graphics recommends that you do so. 
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The feedback data on the GT basically consists of an array of shorts, the first 
of which is the command type, followed by a command length, and then a 
series of sets of 8 shorts containing x, y, zhigh, zlow, red, green, blue, and 
alpha values. If the zhigh and zlow data is packed together, 24 significant 
bits of depth information is available. For a detailed description of the new 
feedback format, see the GT Graphics Library User’s Guide. 

The new Geometry Engines do not perform the xf pt (transform point) 
subroutines, so you cannot use them in feedback mode. However, there is a 
very simple conversion to completely portable Graphics Library code. The 
xf pt subroutines multiplied their arguments by the top matrix on the stack, 
and left the result in the feedback buffer. To port this code, replace the 
beginf eedback call by a getmatrix call, and each xfpt subroutine can 
be converted to a call that does a matrix multiplication of the argument by 
the matrix returned by getmatrix. The resulting values should then be 
written to the appropriate data structures (wherever the subroutines that 
parsed the raw feedback buffer would have put them). You should also 
remove the endf eedback subroutine. This conversion should both speed 
up the code, and make it completely portable. See the example below. 

/* this code transforms the point (x, y f z) by the matrix 

* at the top of the stack, and returns the value in 

* xformedpoint . 

*/ 


float x, y, z; 
short feedbuf[20]; 
union { 

float floatdata; 
short short data [2 ] ; 

} alignhack; /* for alignment problem */ 

long i; 

float xformedpoint [4 ] ; 
feedback (20, feedbuf ) ; 
xfpt (x, y, z) ; 
endf eedback (feedbuf) ; 
for (i = 0; i < 4; i++) { 

alignhack. shortdata [0] = feedbuf [l+i*2] ; 
alignhack. shortdata [1] = feedbuf [2+i*2] ; 
xformedpoint [i] = alignhack . floatdata; 

} 
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It can be replaced by: 


float mat [4] [4]; 
float xf ormedpoint [ 4 ] ; 
long i; 

getmatrix (mat) ; 
for (i =0; i < 4; i++) 
xf ormedpoint [i] = 

x*mat [i] [0] +y*mat [i] [1] +z*mat [i] [2] +mat [i] [3] ; 


Alternatively, if only a few points are transformed, for each point you can 
use this sequence: 


v4f 

getgpos 


Immediate Mode 

The non-GT supported immediate mode macros to remain compatible with 
older machines. These macros wrote instructions and data directly to the 
hardware, so they were completely hardware dependent. On older machines 
this increased performance, but now there is no performance advantage to 
using them. Since this code makes direct calls to the non-GT hardware, it is 
likely to cause bus errors if run on a GT machine. 

In almost every case, the name of the immediate mode macro was 
im _subroutine, where subroutine was the Graphics Library subroutine. For 
example, the macro corresponding to the draw subroutine was im_draw. 
You can port most immediate mode macros that use standard Graphics 
Library subroutines by removing the im_ prefix. 

Unfortunately, the include files containing the standard immediate mode 
macros also contained some non standard calls used internally by the 
Graphics Library. If your code uses these macros, you need to eliminate 
them and develop a different method to achieve the same result. 
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Texture Patterns 


The GT does not support 64x64-bit texture patterns. This means that 
defpattern will not work with an argument of 64. Applications using the 
64x64-bit texture patterns will have to be converted to use smaller ones. 


Curves 

curveit behaves differently on the GT in two ways: it can generate up to 
255 vertices along a curve (compared to 127 on the non-GT), and it issues 
an implicit move before drawing each new segment. 

In the non-GT products, the Geometry Engines understood only one 
hardware subroutine, “iterate_curve”, which caused one more segment of 
the curve to be drawn. The first Geometry Engine iterated the top matrix on 
the stack, then issued the result as a DRAW token to the rest of the pipe. 
This meant some sort of move subroutine was required to begin the curve; 
otherwise, the first segment of the curve would have been drawn from the 
current graphics position. The crv and crvn subroutines did this 
automatically; with the curveit subroutine, where the user explicitly 
modified the iteration matrix, it was the user’s responsibility to issue an 
appropriate move (0.0, 0.0, 0.0) subroutine. If the move was to 
anywhere but ( 0 . 0 , 0 . 0 , 0 . 0 ) , the first segment of the curve would have 
a discontinuous jump. 

In the GT architecture, the curveit subroutine automatically issues the 
move (0.0, 0.0, 0.0) subroutine, so old code that generates a 
discontinuity will not behave the same way. Also, on the older systems, the 
line stipple would have been continued over a pair of adjacent curveit 
subroutines; on the GT, the pattern will be reset with the second curveit 
subroutine. 


Terminal Communications 

setsiowcomO and setfastcomO were necessary on very early 
machines when they were used as terminals instead of workstations. They 
controlled the communications speed over the network to the remote host 
that was driving the terminal. The calls have been left in for compatibility, 
but they are stubs that do nothing. If your code contains them, delete them, 
and your code will run exactly as it did before. 
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Clearing the Screen and Z-buffer 


Onthenon-GT, czclear combines the functions of clear and zclear. 
This means czclear has these potentially undesirable effects: 

• it changes the current color 

• it uses the current pattern during the color clear 

• it uses the current writemask during the color clear 

• it clears the Z-buffer to the standard value 
czclear has none of these effects on the GT. 


Gamma Correction 

On the non-GT, gamma correction slowed performance in color map mode, 
and used the top 256 colors in RGB mode. The GT does all gamma 
correction in a separate lookup table in hardware. This means gamma 
correction is much faster in color map mode, and you can now use the top 
256 colors in RGB mode. 


2.1.3 Compiling Using the Shared Libraries 

To compile your code so it will run on the GT, follow these steps: 

1. Make all necessary changes that are described in the previous section. 

2. Copy your code onto the GT. 

3. To compile the file source.c and name the executable file source, type: 

cc source.c -o source -lgl_s -lm 


2-8 


Tuning Graphics Code 


IRIS-4D Series 



2.2 Improving the Performance of Your Code 

The new GT hardware offers great performance improvements in these 
areas: 

• it draws points, lines, and polygons up to 10 times faster 

• it accesses pixels up to 10 times faster 

• it performs lighting model calculations done in hardware (i.e., Graphics 
Library lighting) up to 50 times faster 

• it correctly clips colors 

The lighting model and color clipping improvements happen automatically 
(see below). To take advantage of the pixel access and optimize drawing 
speed, you need to use the new high performance Graphics Library 
subroutines. In most cases, converting to the new subroutines is a 
straightforward process. However, if your code is based primarily on display 
lists, the solution is not as simple. This is explained in detail in section 
2.2.2, “Taking Advantage of the New Hardware”. 

2.2.1 Overview of the GT Hardware 

Although the non-GT and GT are in the same product family and the code 
for both machines is almost completely compatible, the underlying 
hardware is very different. In some cases, features in the new hardware 
cause minor incompatibilities. These are described in Section 2.1. 

Important changes have occurred in three graphics hardware subsystems: 
the geometry engines, the vertex buffer, and the rendering hardware. The 
new, high performance subroutines described in section 2.2.2 take 
advantage of these changes. 
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The New Geometry Engine Pipeline 


The Geometry Engine pipeline on the GT is different from earlier versions 
in four ways: 

» the GT has 5 Geometry Engines, while the non-GT have 12-16 

• the GT has vastly superior floating point performance 

0 the GT has a 32-bit wide data path, while the non-GT have a 16-bit wide 
data path 

o the GT’s subroutines and data enter via different ports 

These differences result in a great increase in performance, plus a few 
incompatibilities in areas that are highly hardware dependent. The 
incompatibilities include feedback, curves, and hitcodes, and are covered in 
section 2.1.2, “Working Around Incompatibilities”. The lighting and 
clipping improvements are discussed below. 

The GT does most lighting calculations that use Graphics Library 
subroutines in the Geometry Engines (hardware), while the non-GT do most 
lighting calculations on the CPU (software). If you wrote your own lighting 
models, you may want to convert your code to use the Graphics Library 
subroutines to dramatically improve performance. 

The Geometry Engines used in the non-GT clipped only coordinate data. If 
a shaded polygon was moved off the screen so that a vertex was clipped, the 
shading would often undergo a discontinuity as the color data for the clipped 
point suddenly disappeared. In the GT’s new Geometry Engines, color data 
is correctly clipped, so this clipping anomaly will disappear. Correct 
clipping of color data involves interpolating the color of the vertices of a 
clipped line in the same way that the coordinates of the line are clipped. In 
other words, if the edge of a polygon is clipped exactly in half, and the 
original colors of the ends of the clipped line were black (0, 0, 0), and white 
(255, 255, 255), the clipped midpoint would be assigned a color of about 
(127, 127, 127). 
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The Vertex Buffer 


The non-GT saved transformed vertex data in microcode scratch RAM prior 
to scan conversion by microcoded engines. For many applications, the 
operation of writing to the scratch RAM, processing that data, and writing it 
to the the hardware that draws lines or fills polygons created a performance 
bottleneck. 

The GT solves this problem with a special engine, the polygon processor, 
which is dedicated to scan conversion. The polygon processor uses 
transformed vertex data that is stored in a special vertex buffer to render 
points, lines, and polygons. 

The vertex buffer can contain up to 255 vertices. The amount of space for 
vertices on the non-GT varied from release to release (depending on the 
amount of scratch space left after other features were implemented), but all 
versions had room for at least 255 vertices. The maximum number of 
vertices supported by the hardware was never documented, however, so 
existing applications may draw polygons (either filled or unfilled) with more 
than 255 vertices. Such programs will not work correctly on the GT 
hardware. 

In addition, the vertex buffer implicitly controls line styles. Each time the 
polygon processor draws a line connecting data in the vertex buffer, the line 
style is reset before starting, and then is continued through all the vertices. 
Some incompatibilites can arise with code that explicitly controls line style 
resets. See Section 2.1.2, “Working Around Incompatibilities”, and 
Section 2.2.2, “Taking Advantage of the New Hardware”. 


Rendering Hardware 

The new rendering hardware offers two improvements: 

• faster polygon drawing using new, point sampled polygons 

• faster pixel access 

The hardware draws point sampled polygons much more efficiently, and 
draws smooth shaded, connected polygons much better. Point sampled 
polygons look slightly different from those drawn by the non-GT; they tend 
to have fewer pixels turned on. This makes them slightly incompatible with 
polygons drawn by the non-GT. However, a point sampled polygon that is 
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outlined by drawing a line of the same color about it appears the same as 
polygons rendered on the earlier machines. Silicon Graphics offers a 
compatibility mode that outlines the polygons to achieve this effect. See 
Section 2.2.2, “Taking Advantage of the New Hardware”. 

The new hardware also provides a faster mechanism and new subroutines 
for both pixel reading and writing. The older subroutines are still available, 
but are less efficient. Code that makes heavy use of frame buffer access 
should be converted to use the new style pixel routines. See Section 2.2.2, 
“Taking Advantage of the New Hardware”. 

Finally, the rendering hardware on the GT does not support 64 by 64 texture 
patterns. 


2.2.2 Taking Advantage of the New Hardware 

To achieve the highest possible performance on the GT, follow these 
guidelines: 

• Convert all drawing subroutines to the high performance versions. This 
means you will use point sampled polygons (which look slightly 
different), and will not use display lists. Read ‘ ‘Working with Point 
Sampled Polygons” and “About Display Lists”, below, to understand 
what this means, then see “Using High Performance Drawing 
Subroutines”, below, to leam how to perform the conversion. 

• Convert all pixel access subroutines to the high perfoimance versions; see 
“Using High Performance Pixel Subroutines”, below. 

• Use the Graphics Library lighting subroutines; see the GT Graphics 
Library User’s Guide. 

If you elect not to convert to the high performance drawing routines, you 
can easily speed up polygon drawing by using point sampled polygons. To 
do this, you must turn off the compatibility mode that draws point sampled 
polygons that are outlined by hollow polygons of the same color. See 
“Working with Point Sampled Polygons”, below. 

This table lists the old subroutines and their new, high performance 
counterparts. The following sections show how to convert your code to the 
new subroutines. 
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Technique 

Old Subroutines 

New Subroutines 

draw connected 
line segments 

move, draw, draw 

bgnline, v3f , v3f , 

endline 

draw closed 
hollow polygons 

move, draw, draw 

or poly 

bgnclosedline, v3f , v3f , 

endclosedline 

draw filled 
polygons 

pmv, pdr, pdr, pclos 

polf or splf 

bgnpolygon, v3f , v3f , 
endpolygon 

draw points 

pnt , pnt 

bgnpoint, v3f , v3f , 

endpoint 

read pixels 

readpixels, readRGB 

rectread, lrectread 

write pixels 

writepixels, writeRGB 

rectwrite, lrectwrite 

draw triangular 
meshes 

new 

bgntmesh, v3f , v3f , 

endtmesh 

color(vector) 

RGBcolor 

cpack or c3i 

surface normal 

normal 

n3f 

clear screen, 
Z-buffer 

clear, zclear 

czclear 

create RGB 

writemask 

RGBwritemask 

wmpack 


Table 2-3. Comparison of Old and New Subroutines 


Using High Performance Drawing Subroutines 

As shown in Table 2-3, any code that uses the current pnt (point), move, 
draw, pmv, pdr, poly, polf , or splf subroutines is a candidate for 
change. In many cases, the conversion is simple — just change the code to 
use the new subroutines. Unfortunately, the new high performance 
subroutines do not work in display lists, so if your code is based primarily 
on display lists, the solution is not so simple. See the section on display 
lists, below. Also, point sampled polygons produce a slightly different 
visual effect. See the section on point sampled polygons, below. 

The design of all the GT graphics hardware was optimized for a slightly 
different mode of geometric representation which simplifies the Graphics 
Library, and allows for future expansion. Instead of having a separate 
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subroutine for each version (2D integer, 2D floating point, 3D integer, etc.), 
for points, lines, and polygons, there is a single vertex subroutine that comes 
in all these flavors which is interpreted differently depending on where it 
appears in the code. 

To draw a 3D filled polygon whose vertices are floating point numbers, use 
this sequence: 


bgnpolygon 

v 3 f ( 3D , floating point vertex) 

v3f 

v3f 

endpolygon 


The vertex subroutines are interpreted as the vertices of the polygon. To 
draw a 2D polygonal line (hollow polygon) whose vertices are integers, use 
this sequence: 


bgnclosedline 

v 2 i ( 2D, integer vertex) 

v2i 

v2i 

endclosedline 


Many other similar structures are possible. With this structure, only one 
subroutine (the vertex subroutine) has to come in all flavors, and the types 
can be mixed within one polygon or polygonal line. 

The vertex subroutines all take arrays of the appropriate type as arguments 
so that only one parameter (the pointer to the array) needs to be passed per 
call. Future performance improvements are also possible since the data is in 
a known structure within the memory. 

Also, with the high performance subroutines, the concept of a current 
graphics position does not make much sense. The vertex information 
between the bgn* and end* subroutines completely determines the 
geometry to be drawn, and the final location of any current graphics position 
would be ignored by the next high performance subroutine. For 
compatibility, a current graphics position is maintained by the geometry 
engines when only old style drawing subroutines are used, but every one of 
the new high performance subroutines leaves the current graphics position 
unpredictable. The only exception to this rule occurs when you call v3f 
when no drawing mode is active. In this case, it sets the current graphics 
position. 
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The following code fragment draws a red triangle outlined in blue: 

float polydata [3] [2] = {{1.0, 0.0}, {1.0, 1.0}, {0.0, 1.0}}; 

color (RED) ; 
polf2(3, polydata); 
color (BLUE) ; 
poly2(3, polydata); 


To draw the same picture using the high performance subroutines, use the 
following code sequence: 

float polydata [3] [2] = {{1.0, 0.0}, {1.0, 1.0}, {0.0, 1.0}}; 

color (RED) ; 
bgnpolygon () ; 
v2 f ( Spolydata [ 0 ] ) ; 
v2f ( Spolydata [ 1 ] ) ; 
v2 f ( &polydata [ 2 ) ) ; 
endpolygon () ; 
color (BLUE) ; 
bgnclosedline () ; 
v2 f ( Spolydata [ 0 ] ) ; 
v2f ( Spolydata [ 1 ] ) ; 
v2f (Spolydata [2] ) ; 
endclosedline () ; 


or: 


float polydata [3] [2] = {{1.0, 0.0}, {1.0, 1.0}, {0.0, 1.0}}; 
long i; 

color (RED) ; 

bgnpolygon ( ) ; 

for (i =0; i < 3; i++) 

v2f (polydata [i] ) ; 

endpolygon ( ) ; 

color (BLUE) ; 

bgnclosedline () ; 

for (i =0; i < 3; i++) 

v2f (polydata [i] ) ; 

endclosedline () ; 
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To convert the following fragment that draws a shaded quadrilateral into 
high performance subroutines: 

float qdata [4] [3] - {{0.0, 0.0, 0.0}, {1.0, 0.0, 0.0}, 
{ 1 . 0 , 1 . 0 , 0 . 0 }, { 0 . 0 , 1 . 0 , 0 . 0 }}; 
short iarray[4] = {0, 100, 150, 100}; 


splf(4, qdata, iarray) ; 


Use: 

float qdata [4] [3] = {{0.0, 0.0, 0.0}, {1.0, 0.0, 0.0}, 
{1.0, 1.0, 0.0}, {0.0, 1.0, 0.0}}; 
short iarray [4] = {0, 100, 150, 100}; 
long i; 


bgnpolygon () ; 
for (i = 0; i < 4; i++) { 
color (iarray [i] ) ; 
v3f ( &qdata [ i ] [ 0 ] ) ; 

} 

endpolygon ( ) ; 


Using High Performance Pixel Subroutines 

Although the old pixel access subroutines are available on the GT, they are 
not tuned to the architecture of the new frame buffer. They will run at least 
as fast as they do on a non-GT, but the new subroutines could increase 
performance by up to 10 times. The new subroutines deal with rectangular 
regions of the screen, so rows of pixels can be read/written by using 
rectangles that are one pixel high. 

This table lists the old pixel subroutines and their new counterparts. 


Technique 

Old Subroutines 

New Subroutines 

read pixels 

readpixels 

rectread 


readRGB 

lrectread 

write pixels 

writepixels 

rectwrite 


writeRGB 

lrectwrite 


Table 2-4. Comparison of Old and New Pixel Subroutines 
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The new subroutines read and write pixels in a standard form — usually 32 
bits of data with the red, green, blue and alpha components packed with the 
red component making up the lowest order 8 bits, the green the next 8 bits, 
and so on. If the value stored in a pixel is a colormap index, it is stored in 
the lowest order 12 bits. For efficiency, the pixel reading/writing software 
does not check the mode of the window from which the data is read; if RGB 
data is written into a colormapped window, strange pictures will result, 
lrectread and lrectwrite read and write 32 bit pixels, rectread 
and rectwrite read and write only the low order 16 bits, and hence 
should be used only for color index data. 

The older pixel subroutines are basically implemented on top of these faster 
subroutines, so in particular, readRGB and writeRGB must unpack and 
pack 8 bit RGB data, so the performance of the old subroutines will not be 
comparable with that of the new ones. The exact conversion that will give 
the best performance is highly application dependent. 


Working with Point Sampled Polygons 

In the vast majority of applications, point sampled polygons look better than 
the older polygons; however, applications that have figured out to the pixel 
exactly what bits to turn on (e.g., for menus and scroll bars) may encounter 
some problems, and “T” shaped intersections of polygons may look 
different. If you want to use the high performance subroutines, but are 
unsure what effect point sampled polygons will produce, turn off 
compatibility mode as described below. 

Silicon Graphics provides a compatibility mode for the old style polygon 
subroutines (e.g., poly, polf, pmv, pdr). This draws a hollow 
polygon to outline the point sampled polygon, which makes it appear 
exactly as it always has. However, there is a severe performance penalty for 
this — as much as twofold for small polygons. The compatibility mode runs 
by default, but, to turn it off to improve performance, you can use the 
glcompat subroutine. Within your main program, add this line: 

glcompat (glc_oldpolygon, FALSE) ; 

This is highly recommended if you use display lists; it dramatically speeds 
up old style polygon subroutines. 
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This compatibility mode does not draw outlines around polygons drawn 
with the high performance subroutines. 


About Display Lists 

The high performance subroutines do not currently compile into display lists 
since the process of testing to see if display list compilation is going on 
costs an instruction. There are some possible techniques that may be used in 
the future to add high performance subroutines to display lists, so for now, 
do not call them between a makeobjanda closeobj. See the previous 
section, “Working with Point Sampled Polygons” to leam how to speed up 
code that uses display lists with the old style polygon subroutines. 

Display lists were originally introduced on our oldest terminal based 
products since that was the only way to achieve acceptable performance. 
Since the introduction of the first workstation, display lists have been 
retained for compatibility, but there is nothing in the display list compilation 
or traversal code that could not have been written by the users. Since 
display lists are meant to be highly flexible and to work in a wide variety of 
applications, they are not as efficient as they could be if they were tailored 
to a particular application. 

Customers who require a display list and at the same time require highest 
performance are encouraged to write their own display list traverser tailored 
to their own needs. 

In the 4D series, there is no problem using display lists, since the CPU is 
fast enough to keep up with the graphics. Even though the display list code 
is inefficient, the graphics is slow by comparison so the graphics is the 
bottleneck, but not by much. With the GT, the graphics speeds up 
enormously, and the traversal of the display list has become the bottleneck. 
Thus, applications that are based on the Graphics Library display lists will 
not achieve full GT performance. If possible, restructure your code so that 
display lists are not required at all, and if this seems impossible, consider 
developing a custom display list format that is tailored to your particular 
application. 
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Converting Line Stippling Code 

The non-GT did not have a vertex buffer, so every line was drawn using the 
hardware subroutines move and draw. The line style hardware could be 
put in two modes. In one mode, the stippling pattern was reset after each 
draw, and in the other, it was not. On the GT, these modes are controlled 
implicitly. When a polygonal line is rendered, the line style is reset, and is 
then continuous for all the vertices in the buffer. If your application requires 
that the line style be reset for each segment of a polygonal line, draw the 
line as a series of segments. In other words, instead of writing: 


bgnline () ; 
v3f (vertl ) ; 
v3f (vert2 ) ; 
v3f (vert3) ; 
v3f (vert4 ) ; 
endline () ; 

Use: 

bgnline () ; 
v3f (vertl) ; 
v3f (vert2) ; 
endline () ; 
bgnline () ; 
v3f (vert2) ; 
v3f (vert3) ; 
endline () ; 
bgnline () ; 
v3f (vert3) ; 
v3f (vert4 ) ; 
endline () ; 


Another incompatibility can arise if the code to be ported has is reset set 
to FALSE, and polygonal lines are drawn with a move subroutine followed 
by a series of draw subroutines. Since the vertex buffer architecture must 
be used, and there is no way of telling which draw is the last one, each 
draw subroutine effectively flushes out the vertex buffer. Each time the 
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vertex buffer is flushed, the line style is reset, so continuous stippling is 
impossible. In this case, the code must be converted to the high 
performance version to achieve the same effect. As an example, consider 
the following code fragment, and its high performance version: 

lsreset (FALSE) ; 

move2 (data [ 0] [ 0] , data[0][l]); 
draw2 (data [1] [0] f data[l][l]); 
draw2 (data [2] [0] , data[2][l]); 
draw2 (data [3] [0] , data [3] [1 ] ) ; 

Here is the high performance version of the same code: 

bgnline () ; 
v2f (Sdata [0] [0] ) ; 
v2f (&data [1 ] [0] ) ; 
v2f (&data [2 ] [0] ) ; 
v2f (&data [3 ] [0] ) ; 
endline () ; 
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3. Porting 4D Code to the Persona! 

IRIS 


This chapter is divided into two sections. The first section describes 
changes that you may need to make to your code to make it run on the 
Personal IRIS. The second section gives you tips for increasing the 
performance of your code. 


3.1 Making Your Code Run on the Personal 
IRIS 

This section shows you how to make code that mns on non-GT and GT 
systems run on the Personal IRIS. The first section contains information 
important to anyone who is porting to the Personal IRIS; the second section 
is for people porting from a non-GT, and the third is for people porting from 
a GT. 


3.1 .1 Porting from Any 4D 

The Personal IRIS and all other 4D machines are different in four areas: the 
screen cursor, audio chip, number of bitplanes, and feedback data. 
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One-Color Cursor 


The Personal IRIS comes standard with a single-bit cursor. This provides 
two colors, but, since one of the colors is clear, for all practical purposes it’s 
a one-color cursor. You can assign any color you want to the cursor (using 
mapcolor) but you can’t display a cursor composed of two or three colors. 

Any instructions that manipulate the upper bit of a two-bit cursor or map 
cursor colors 2 or 3 will be ignored. 

For example, say your application currently maps these colors: 


cursor 

color 

0 

is 

clear 

cursor 

color 

1 

is 

red 

cursor 

color 

2 

is 

green 

cursor 

color 

3 

is 

blue 


On the Personal IRIS, the cursor will appear only in red; color 2 will be 
mapped to clear, and color 3 will be mapped to red. 


Audio Chip 

The Personal IRIS contains an audio chip, so new applications can take 
advantage of sound generation. This won’t, however, affect existing 
applications being ported to the Personal IRIS. 


Feedback Data 

Check whether your application uses any of these feedback subroutines: 


feedback 

endfeedback 

passthrough 

If it does, the data these subroutines return will be different on the Personal 
IRIS than on a GT; see Chapter 17 of the GT Graphics Library User’s 
Guide, Version 1.1, for details. Silicon Graphics, Inc. recommends that you 
avoid using these three subroutines if you want your application to be 
portable to all 4D machines. 
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Available Colors 


The Personal IRIS may have less bitplane space available than your current 
system. With the minimum configuration on the Personal IRIS of 8 
bitplanes, only 16 colors are available in double buffer mode. This 
limitation may affect your application. 

To determine how many bitplanes are available to you, use the hardware 
inventory command: 


hinv 


If you see “Bit-plane option installed” in the listing, you have 24 bitplanes. 
If you do not see this, you have 8 bitplanes. 


3.1.2 Porting from a Non-GT 


To make your current non-GT code run on a Personal IRIS, you need to 
follow two steps: 

1 . Check whether the code uses any of these incompatible subroutines: 


clearhitcode 

curveit 

czclear 

defpattern 

feedback 

endf eedback 

gethitcode 

getlsbackup 

getresetls 


gRGBcursor 

lsbackup 

passthrough 

RGBcursor 

resetls 

xfpt 

setslowcom 

setfastcom 


If it doesn’t, go to step 2. If it does use incompatible subroutines, see 
Chapter 2, Section 2.1.2, “Working Around Incompatibilities”. 

2. Compile your code using the shared libraries. To compile the file 
sources and name the executable source, type: 


cc source. c -o source -lgl_s -lm 


If you are also interested in increasing the performance of your code, see 
Section 3.2. 
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3.1.3 Porting from a GT 


The Graphics Library subroutines for the GT and Personal IRIS are nearly 
identical. Application software developed for and running on a GT will not, 
in most cases, require any change to run on the Personal IRIS. You should 
be aware of the following differences between the two machines. 


Alphablending 

The Personal IRIS doesn’t use alphablending — any process that relies on it 
won’t work the same way on the Personal IRIS. An application that used 
alphablending (i.e., used the blendf unction subroutine) to render a 
transparent car windshield, for instance, would need to be modified to run 
on the Personal IRIS. 


Limited Writing to Z-Buffer 

The Personal IRIS won’t allow an application to draw into the Z-buffer, but 
you can write pixels to the Z-buffer. The zdraw subroutine works with 
only these pixel-writing subroutines: 


writepixels 

writergb 

rectwrite 

lrectwrite 


Also, if your code includes the zsource subroutine, note that the Personal 
IRIS ignores this subroutine. 


3.2 Improving the Performance of Your Code 

Use the information in this section to increase performance when you write 
pixels or clear your Z-buffer. 
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3.2.1 Using the High Performance Pixel Routines 


You can greatly increase the performance of applications that use the 
readRGB and writeRGB subroutines by replacing these subroutines with 
lrectread and lrectwrite, respectively. 


3.2.2 Improving Performance of Z-buffer Clearing 

The czclear subroutine works much faster on the Personal IRIS when you 
use certain values, czclear takes two values: 

czclear (color value, z value) 

To improve performance, use these z values: 

• 0x7fffff when the z function you’re using is zf_less or 

ZF_EQUAL 

• Oxff 800000 when the zfunction is ZF_GREATER or ZF_GEQUAL 

See the GT Graphics Library Reference Manual, Version 1. 1 for more 
information on czclear and zfunction. 
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3. Porting 4D Code to the Personal 
IRIS 


This chapter is divided into two sections. The first section describes 
changes that you may need to make to your code to make it run on the 
Personal IRIS. The second section gives you tips for increasing the 
performance of your code on either a standard Personal IRIS, or on a 
Personal IRIS with the Turbo option. 


3.1 Making Your Code Run on the Personal 
IRIS 

This section shows you how to make code that runs on non-GT and GT 
systems run on the Personal IRIS. The first section contains information 
important to anyone who is porting to the Personal IRIS; the second section 
is for people porting from a non-GT, and the third is for people porting from 
aGT. 


3.1 .1 Porting from Any 4D 

The Personal IRIS and all other 4D machines are different in four areas: the 
screen cursor, audio chip, number of bitplanes, and feedback data. 
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One-Color Cursor 


The Personal IRIS comes standard with a single-bit cursor. This provides 
two colors, but, since one of the colors is clear, for all practical purposes it’s 
a one-color cursor. You can assign any color you want to the cursor (using 
mapcolor) but you can’t display a cursor composed of two or three colors. 

Any instructions that manipulate the upper bit of a two-bit cursor or map 
cursor colors 2 or 3 will be ignored. 

For example, say your application currently maps these colors: 


cursor 

color 

0 

is 

clear 

cursor 

color 

1 

is 

red 

cursor 

color 

2 

is 

green 

cursor 

color 

3 

is 

blue 


On the Personal IRIS, the cursor will appear only in red; color 2 will be 
mapped to clear, and color 3 will be mapped to red. 


Audio Chip 

The Personal IRIS contains an audio chip, so new applications can take 
advantage of sound generation. This won’t, however, affect existing 
applications being ported to the Personal IRIS. 


Feedback Data 

Check whether your application uses any of these feedback subroutines: 


feedback 

endfeedback 

passthrough 

If it does, the data these subroutines return will be different on the Personal 
IRIS than on a GT; see Chapter 17 of the GT Graphics Library User’s 
Guide, Version 1.1, for details. Silicon Graphics, Inc. recommends that you 
avoid using these three subroutines if you want your application to be 
portable to all 4D machines. 
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Available Colors 


The Personal IRIS may have less bitplane space available than your current 
system. With the minimum configuration on the Personal IRIS of 8 
bitplanes, only 16 colors are available in double buffer mode. This 
limitation may affect your application. 

To determine how many bitplanes are available to you, use the hardware 
inventory command: 

hinv 


If you see “Bit-plane option installed” in the listing, you have 24 bitplanes. 
If you do not see this, you have 8 bitplanes. 


3.1.2 Porting from a SMon-GT 


To make your current non-GT code run on a Personal IRIS, you need to 
follow two steps: 

1. Check whether the code uses any of these incompatible subroutines: 


clearhitcode 

curve it 

czclear 

defpattern 

feedback 

endf eedback 

gethitcode 

getlsbackup 

getresetls 


gRGBcursor 

lsbackup 

passthrough 

RGBcursor 

resetls 

xfpt 

setslowcom 
setf astcom 


If it doesn’t, go to step 2. If it does use incompatible subroutines, see 
Chapter 2, Section 2.1.2, “Working Around Incompatibilities”. 

2. Compile your code using the shared libraries. To compile the file 
sour c e.c and name the executable source, type: 


cc source. c -o source -lgl_s -lm 


If you are also interested in increasing the performance of your code, see 
Section 3.2. 
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3.1.3 Porting from a GT 


The Graphics Library subroutines for the GT and Personal IRIS are nearly 
identical. Application software developed for and running on a GT will not, 
in most cases, require any change to run on the Personal IRIS. You should 
be aware of the following differences between the two machines. 


Alphablending 

The Personal IRIS doesn’t use alphablending — any process that relies on it 
won’t work the same way on the Personal IRIS. An application that used 
alphablending (i.e., used the blendf unction subroutine) to render a 
transparent car windshield, for instance, would need to be modified to run 
on the Personal IRIS. 


Limited Writing to Z-Buffer 

The Personal IRIS won’t allow an application to draw into the Z-buffer, but 
you can write pixels to the Z-buffer. The zdraw subroutine works with 
only these pixel- writing subroutines: 


writepixels 

writergb 

rectwrite 

lrectwrite 


Also, if your code includes the zsource subroutine, the Personal IRIS 
ignores this subroutine, but it works correctly on the Personal IRIS with the 
Turbo option. 


3.2 Improving the Performance of Your Code 

This section shows you how to use pixel routines and z-buffer clearing to 
improve performance on all Personal IRIS workstations. It also describes 
the Turbo option and additional performance increases you can realize using 
this option. 
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3.2.1 Improving Performance on All Personal IRISes 


Use the information in this section to increase performance when you write 
pixels or clear your Z-buffer. 


Using the High Performance Pixel Routines 

You can greatly increase the performance of applications that use the 
readRGB and writeRGB subroutines by replacing these subroutines with 
lrectread and lrectwrite, respectively. 


Improving Performance of Z-buffer Clearing 

The czclear subroutine works much faster on the Personal IRIS when you 
use certain values, czclear takes two values: 

czclear (color value, z value) 

To improve performance, use these z values: 

• 0x7fffff when the zfunction you’re using is zf_less or 

ZF_LEQUAL 

• -0x800000 when the zfunction is ZF_GREATEROr ZF_GEQUAL 

See the GT Graphics Library Reference Manual, Version 1.1 for more 
information on czclear and zfunction. 


3.2.2 Improving Performance on a Personal IRIS with 
Turbo Option or RE2 

If your Personal IRIS has the Turbo option, you can improve the drawing 
speed of lines, polygons, NURBS, and splines by up to four times their 
current speed. Also, the Turbo option and all new Personal IRISes come 
with the new Raster Engine (the RE2) which increases the performance of 
all pixel-writing routines, and lets you specify logical operations for pixel 
writes using the new Graphics Library routine, logicop ( ) . (See the 
Graphics Library Programming Guide for more information.) 
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To check what type of hardware you have, type: 

hinv 

You have the RE2 if you see a line that starts with this: 

Graphics Board: GR1 . 2 

You have the Turbo option (which includes RE2) if you see this line: 

Graphics Board: GR1 . 2 other options Turbo option installed. 


Turbo Hardware Overview 

A standard Personal IRIS has only one floating point processor, and the RE1 
chip. The Turbo option is a set of boards that includes four floating point 
processors and the RE2 chip. 

Without changing your code at all, you’ll realize a 20-30% increase in 
overall graphics throughput due to the extra floating point processors, and 
any code that uses rectwrite, writepixels, or re ct zoom will run 
two to three times faster due to the RE2. 


Improving Drawing Speeds 

You get the most out of the parallel processing power of the four floating 
point processors by clustering like groups of drawing routines. The drawing 
speeds of large lines and polygons are limited by the RE2 so, while 
clustering will help, you’ll see the biggest improvement on small lines and 
polygons. Using triangle meshes rather than regular polygons also increases 
speed. 

The Turbo hardware also supports drawing shaded lines; the software 
routine that supports this is shademode 1 . On all IRIS systems, 
shademodei is automatically set to gouraud so, if the system’s hardware 
supports shaded lines, it draws all lines shaded. Because the standard 
Personal IRIS does not support shaded lines, it draws all lines as if 
shademodei were set to flat. If you want to draw lines on the Turbo as 
quickly as possible (and don’t need them to be shaded), explicitly set 
shademodei (FLAT) . 
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Increasing the Precision of Color Index Shading 


When you render shaded polygons in color index mode, the RE2 will 
produce more accurate results. You can take advantage of this with the new 
Graphics Library routine, colorf ( ) . It lets you set the vertex colors of 
each polygon with fractional precision. The IRIS simulates the fractional 
color by drawing a mixture of two adjacent integer colors; this color mixing 
is called dithering. With the RE2, dithering is always turned on when you 
are drawing in depthcue mode, or with shademodel (GOURAUD) . The 
floating point value is rounded to the nearest integer when you use 
colorf () on a standard Personal IRIS without RE2. 


Increasing the Qualify of Anti-aliased Lines 

The RE2 lets you increase the quality of all anti-aliased lines in two ways: it 
supports both subpixel positioning and color comparisons. You can 
increase the quality of anti-aliased lines on RE1 and RE2 systems by 
changing the gamma value (the brightness of colors) of your screen. 

Subpixel positioning lets you draw more accurate anti-aliased lines by 
allowing the beginning of a line to fall between two pixels. You enable this 
with these two lines of code: 

subpixel (ON) ; 
line smooth (ON) ; 

See the man pages that describe these routines in detail. Note that using 
these routines will degrade the drawing speed. 

The RE2 also improves the quality of intersecting anti-aliased lines by 
comparing the relative brightness of the values assigned to a pixel, then 
drawing only the brighter value. You enable color comparison with these 
three lines of code: 

zbuf fer (ON) ; 
z function (ZF_GREATER) ; 
z source (ZSRC_COLOR) ; 

See the man pages that describe these routines in detail. 
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Finally, increasing the gamma value of your screen colors (i.e., increasing 
the saturation of the colors), greatly improves the look of anti-aliased lines. 
The default gamma value is 1.7; you get best results for anti-aliased lines by 
setting it to 2.4 by typing: 

gamma 2 . 4 
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